Twilio Voice JavaScript SDKを使って電話の発信、着信をしてみる

#Twilio

酒匂祐也

2021.07.11

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

Twilio Programmable Voiceでは、APIを使ったり、SDKを使ったりして、下記のように電話の発信、着信などを行うことができます。

発信の場合

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = require('twilio')(accountSid, authToken);

client.calls
      .create({
         twiml: '<Response><Say>Ahoy, World!</Say></Response>',
         to: '+14155551212',
         from: '+15017122661'
       })
      .then(call => console.log(call.sid));

着信の場合

const express = require('express');
const VoiceResponse = require('twilio').twiml.VoiceResponse;

const app = express();

// Create a route that will handle Twilio webhook requests, sent as an
// HTTP POST to /voice in our application
app.post('/voice', (request, response) => {
  // Use the Twilio Node.js SDK to build an XML response
  const twiml = new VoiceResponse();
  twiml.say({ voice: 'alice' }, 'hello world!');

  // Render the response as XML in reply to the webhook request
  response.type('text/xml');
  response.send(twiml.toString());
});

// Create an HTTP server and listen for requests on port 3000
app.listen(3000, () => {
  console.log(
    'Now listening on port 3000. ' +
    'Be sure to restart when you make code changes!'
  );
});

と言いましても、実際に電話応対で使うには下記のことなどをしないといけません。

発信して、発信先が応答したらどうするか？
- 発信先と発信元で通話を確立させる
着信したら、どうするのか？
- 対応できる担当者に着信させる

この場合、ソフトフォンと呼ばれる電話操作を行うための画面を作る必要があります。

Twilioは各種APIが提供されているのでAPIを呼び出すことができれば自由に作ることができますが、SDKも提供されております（SDKを使うと開発しやすいです）。

iOS SDK
Android SDK
JavaScrip SDK

ウェブアプリの場合はJavaScript SDKを使うことになります。SDKは使いやすいですが、アプリケーションをイチから作成するのは大変だったりもします。しかし、ありがたいことにTwilio社はサンプルアプリケーションを公開しておりますので、それを参考に開発するのが良いと思います。

サンプルアプリケーションについて

こちらを使用します。

https://github.com/TwilioDevEd/voice-javascript-sdk-quickstart-node

電話を発信または着信するまでの流れ

こちらの記事にある画像を使って説明します。

https://www.twilio.com/docs/voice/sdks/javascript

発信する場合

物理的な電話機（ハードフォン）を使って発信する場合は、電話機に発信先の電話番号を入力して、そこから発信することになります。相手が応答すれば、その結果を電話機が受け取って通話が確立します。

Twilioの場合は、電話機の代わりにTwilioに発信の要求をして、Twilioから発信することになります（図の真ん中のアイコンがTwilioです）。発信して、相手が応答したらText To Speech（TTS）のメッセージを流して終わりならば、発信とTTS処理を記載したソースコードを書けば終わりです。

そうではなく、相手が応答したら通話をしたいという場合は、Twilioに発信の要求をするソースコードを書くだけでは終わりません。発信したら、その結果をTwilioが返してくるので、それを受けてどうするか？という処理を書かないといけません。具体的には発信が確立したイベント（acceptイベント）や切断されたイベント（disconnectイベント）などをフックして必要な処理を書いていきます。

これは図の Your Web Application + Twilio JS SDK と Twilio との処理になります。

着信する場合

物理的な電話機（ハードフォン）を使って着信する場合は、そこに電話がかかってきたら応答するなり、拒否するなりすることになります。

Twilioの場合は、まずTwilioに電話がかかってきます。そのことをTwilioがイベントで教えてくれます。着信したらText To Speech（TTS）のメッセージを流して終わりならば、着信イベントをフックする処理とTTS処理を記載したソースコードを書けば終わりです。

そうではなく、着信したら応答として通話を確立したいという場合は、Twilioからの着信イベントを受けて、どのような処理をするかをTwilioに返す必要があります。それを行うことでアプリケーション（Your Web Application + Twilio JS SDK）に着信させたり、電話番号に転送したりすることができます。

図に記載されている説明を補足しますと、最初にTwilioが着信を受けて、着信イベントを通知してくれます。このイベントは具体的にはWebhookです。そのため、これを受けるためのウェブアプリケーションが必要です。それが図にある Your Backend です。ここで着信イベントを受けたら、そのあとどうするかをTwilioに返します。返し方として、TwiMLというTwilioへ指示するためのマークアップ言語を使うと、いろいろなことができます。

例えば着信だと、以下のようなことをします。

携帯電話などに転送する
- この場合はTwilioから携帯に転送されるので、転送された電話に応答してからは、Twilioの管理を離れます。
SIPクライアントに着信させる
- TwilioにはSIPクライアントを登録して（レジストして）発信、着信を行える機能がありますので、ある特定のSIPクライアントに着信させることができます。この場合、具体的にはSIPクライアントに発信する処理を行います。
アプリケーションに着信させる
- 今回話題にする内容ですが、電話応対アプリなどソフトフォンに着信させる方法です。これは具体的にはデバイス（Device）としてTwilioに登録されている（レジストされている）ものに対して発信する処理を行います。図では Your Web Application + Twilio JS SDK が電話応対アプリなどソフトフォンに該当するものなのですが、このアプリを最初にデバイス（Device）としてTwilioに登録（レジスト）します。それにより、Twilioからデバイスに発信することができ、つまりは着信を受けることができるのです。

ちなみに言い方を変えると、Twilioは下記の3つのいずれかに発信することができます。

電話番号（携帯など）
SIPクライアント（TwilioにレジストされているSIPクライアント）
デバイス（Twilioにレジストされているデバイス）

発信APIの説明文を引用すると、こうなります。

The phone number, SIP address, or client identifier to call.

さて、今回は前置きが長くなりましたが、このあとはサンプルアプリケーションをセットアップして実際に動かしてみます。

作業環境の準備

node.js

version 14.0以上が必要です。直接インストールするか、nvmを使ってインストールしておきます。

nvm
- https://github.com/nvm-sh/nvm

ngrok

今回はローカル環境のソースを動かすのですが、インターネット経由でのアクセスが必要なため使用します。

ngrokのサイトでサインアップし、インストールします。

ngrok
- https://ngrok.com/

ブラウザ

WebRTCに対応しているブラウザが必要です。Google Chrome や Mozilla Firefoxが候補になります。

サンプルアプリケーションのセットアップ

TwiML アプリケーションの作成

Twilioコンソールのメニューから Programmable Voice > TwiML > TwiML Apps を選択します。

Create new TwiML App ボタンを押します。

Friendly Name に任意のものを入力して、他の項目はあとで設定しますので Create ボタンを押します。

作成した TwiML Appを選択して TwiML App SID を控えておきます。

電話番号の購入

Twilioコンソールのメニューから Phone Numbers を選択します。

Active Numbers を選択して画面上の Buy a Number を選択します。

番号を購入したい国を Country 欄で選択します。 Search ボタンを選択します。

購入可能な電話番号が一覧に表示されます。購入したい番号の行にある Buy ボタンを選択します。

確認画面が表示されますので、 Next ボタンを選択します。

番号の利用者が Business なのか Indivisual なのか選択します。選択したら Next ボタンを選択します。

日本の電話番号を購入する場合は、本人情報をTwilio上に登録し、Twilio社のレビュープロセスを完了させておく必要があります。（参考）https://github.com/neri78/Twilio-HandsOn-101-JP/blob/master/docs/00-Misc/00-00-IdentitySid.md

承認を得ている住所情報を選択して、 Buy ボタンを選択します。

API Keyの作成

Twilioコンソールのメニューから Console Dashboard > API Keys を選択します。

+ ボタンを押します。

Friendly Name に任意のものを入力して、 Create API Key ボタンを押します。

画面に表示されている SID と SECRET を控えておきます。特にメッセージが出ている通り SECRET は二度と確認することができません。

SID と SECRET を控えたら、 Got it! I Have・・・ のところにチェックをつけます。チェックをつけると Done ボタンが押せるようになりますので、押します。

API Keyが作成されました。

サンプルアプリケーションのソースコードをダウンロード

下記のリポジトリからダウンロードします。

git clone https://github.com/TwilioDevEd/voice-javascript-sdk-quickstart-node.git

依存するライブラリのインストール

プロジェクトディレクトリに移動します。

cd voice-javascript-sdk-quickstart-node

下記を実行します。

npm install

node_modulesにある `twilio.min.js` を `public` ディレクトリにコピー

Twilio Voice ClientのSDKファイルを下記コマンドでコピーします。

cp node_modules/@twilio/voice-sdk/dist/twilio.min.js public

これは、サンプルのソフトフォン画面である public/index.html で読み込むためです。

・・略・・
    <script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
    <script type="text/javascript" src="twilio.min.js"></script>
    <script src="quickstart.js"></script>
  </body>
</html>

envファイルの編集

envファイルを編集するため、デフォルトの .env.example から .env を作成します。

cp .env.example .env

下記の値を設定します。

設定項目	値
TWILIO_ACCOUNT_SID	Twilioコンソールのダッシュボード画面で確認できます。
TWILIO_TWIML_APP_SID	作成したTwiml アプリケーションのSIDを設定します。
TWILIO_CALLER_ID	購入した電話番号を E.164形式で設定します。（例）+815012345678
TWILIO_API_KEY	作成したAPI KEYを設定します。
TWILIO_API_SECRET	作成したAPI KEYを設定します。